home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 051-060 / amok56 / turbofiles_v2.0 / (turbo)files.doc next >
Text File  |  1993-11-04  |  10KB  |  231 lines
  1. DEFINITION (Turbo)Files V2.0;
  2.  
  3. CONST (* Modus for Open() *)
  4.   newFile = TRUE;
  5.   oldFile = FALSE;
  6.  
  7. CONST (* content of f.res *)
  8.   done         = 0; (* all ok, no error *)
  9.   notdone      = 1; (* unknown error *)
  10.   notOpen      = 2; (* Open() has not opened the file or Close() closed it*)
  11.   openError    = 3; (* error while opening the file *)
  12.   readError    = 4; (* disk corrupt *)
  13.   writeError   = 5; (* disk corrupt, disk full *)
  14.   seekError    = 6; (* error by using SetPos() *)
  15.   endOfFile    = 7; (* end of File *)
  16.   outOfMem     = 8; (* not enough memory, buffer of Open() too big *)
  17.   notExists    = 9; (* file to open not found *)
  18.  
  19. CONST (* Modes of SetPos() *)
  20.   beginning = Dos.beginning;
  21.   current   = Dos.current;
  22.   end       = Dos.end;
  23.  
  24. TYPE
  25.   File = RECORD
  26.     res : SHORTINT;
  27.   END;
  28.  
  29. PROCEDURE Open(VAR f: File; name: ARRAY OF CHAR;
  30.                bufferSize: LONGINT; new: BOOLEAN): BOOLEAN;
  31. PROCEDURE ReadBytes (VAR f: File; adr: Exec.ADDRESS; len: LONGINT): LONGINT;
  32. PROCEDURE WriteBytes(VAR f: File; adr: Exec.ADDRESS; len: LONGINT): BOOLEAN;
  33. PROCEDURE ReadChar (VAR f: File; VAR ch: CHAR): BOOLEAN;
  34. PROCEDURE WriteChar(VAR f: File;     ch: CHAR): BOOLEAN;
  35. PROCEDURE Read (VAR f: File; VAR block: ARRAY OF BYTE): BOOLEAN;
  36. PROCEDURE Write(VAR f: File;     block: ARRAY OF BYTE): BOOLEAN;
  37. PROCEDURE ReadString (VAR f: File; VAR str: ARRAY OF CHAR): INTEGER;
  38. PROCEDURE WriteString(VAR f: File;     str: ARRAY OF CHAR): BOOLEAN;
  39. PROCEDURE WriteLn(VAR f: File): BOOLEAN;
  40. PROCEDURE Size(VAR f: File): LONGINT;
  41. PROCEDURE GetPos(VAR f: File): LONGINT;
  42. PROCEDURE SetPos(VAR f: File; offset: LONGINT; mode: LONGINT): BOOLEAN;
  43. PROCEDURE Search(VAR f: File; str: ARRAY OF BYTE; len: INTEGER): LONGINT;
  44. PROCEDURE Close(VAR f: File): BOOLEAN;
  45.  
  46. PROCEDURE Code(fileName, codeWord: ARRAY OF CHAR; decode: BOOLEAN):BOOLEAN;
  47. PROCEDURE DeleteFile(name: ARRAY OF CHAR): BOOLEAN;
  48. PROCEDURE Exists(name: ARRAY OF CHAR; VAR size: LONGINT): BOOLEAN;
  49.  
  50. This Module is a replacement for the Oberon module FileSystem. It simplifies
  51. and accellerates the access to files. The modules Files and TurboFiles beha­
  52. ves  in the same way, but TurboFiles is a little bit quicker because the im­
  53. portant procedures are written in Assembler. Files.mod  is  only  for  those
  54. people  who hate Assembler. All other should only use the Module TurboFiles.
  55. Because TurboFiles has an assemblerpart,  You  have  to  Assemble  the  file
  56. TurboFiles.asm (With A68k) and then You can use the CLI-command JOIN to jo­
  57. in TurboFiles.obj(s) and the assemblerpart TurboFiles.o:
  58.  
  59. JOIN TurboFiles.obj TurboFiles.o AS TF.obj
  60. COPY TF.obj TO TurboFiles.obj
  61.  
  62. Now  You  can  use  TurboFiles.obj  like an Oberon-Modul. TurboFiles uses no
  63. static variables and respects the Amiga-Dos register-conventions, (only  D0,
  64. D1  A0  and  A1  are changed by the Assembler-code) so You can make programs
  65. which uses TurboFiles resident with  ARP.Ares  or  Resident  and  start  the
  66. programs multiple times, if You have compiled it with the small-data option
  67.  
  68. If  one of the following procedures returns the boolean value TRUE, then the
  69. operation was successful and the field f.res has the value done. If an error
  70. occurs, for example that You try to read over the end of the file, then  the
  71. used procedure will set f.res to a value unequal done and all following pro­
  72. cedure-calls (except  Close()) will be ignored. In this case You can look at
  73. f.res to find the reason for the error. f.res can have one of the  following
  74. values:
  75.  
  76. CONST (* content of f.res *)
  77.   done         = 0; (* all ok, no error *)
  78.   notdone      = 1; (* unknown error *)
  79.   notOpen      = 2; (* Open() has not opened the file or Close() closed it*)
  80.   openError    = 3; (* error while opening the file *)
  81.   readError    = 4; (* disk corrupt *)
  82.   writeError   = 5; (* disk corrupt, disk full *)
  83.   seekError    = 6; (* error by using SetPos() *)
  84.   endOfFile    = 7; (* end of File *)
  85.   outOfMem     = 8; (* not enough memory, buffer of Open() too big *)
  86.   notExists    = 9; (* file to open not found *)
  87.  
  88. PROCEDURE Open(VAR f: File; name: ARRAY OF CHAR;
  89.                bufferSize: LONGINT; new: BOOLEAN): BOOLEAN;
  90.  
  91. Before  You  can use one of the following procedures, You must open the file
  92. with Open(). Open() opens the Dos-File and  initializes  the  file-variable.
  93. name  is  a  Amiga-Dos  filename like "Text" or "Pictures:pic23". buffersize
  94. determines the size of the used buffer. One kByte should be enough, but when
  95. You write to disk, a large buffer  of  10  or  more  kByte  is  quicker.  IF
  96. new=TRUE,  then  a new file is created, otherwise Open() will try to open an
  97. existing file.
  98.  
  99. The procedures to read from the file:
  100.  
  101. PROCEDURE Read(VAR f: File; VAR block: ARRAY OF BYTE): BOOLEAN;
  102.  
  103. Reads LEN(block) bytes from the file and  stores  it  in  block.  block  is
  104. compatible  to  all  datatypes,  so  this procedure can be used to read any
  105. datas like Records, INTEGERS, ....
  106.  
  107. PROCEDURE ReadChar(VAR f: File; VAR ch: BYTE): BOOLEAN;
  108.  
  109. Reads one single character from the file.The same thing You can do by using
  110. Read(), but TurboFiles.ReadChar() is much quicker than Read().
  111.  
  112. PROCEDURE ReadString(VAR f: File; VAR str: ARRAY OF CHAR): INTEGER;
  113.  
  114. Reads a string from the file using ReadChar(). The end  of  the  string  is
  115. marked  by  0X  or  linefeed  (0AX).  ReadString()  will read not more than
  116. LEN(str) characters. The result is the length of the string.
  117.  
  118. PROCEDURE ReadBytes(VAR f: File; adr: Exec.ADDRESS; len: LONGINT): LONGINT;
  119.  
  120. This is a low-level-procedure, because Exec.ADDRESS  is  used.  You  should
  121. only  use this procedure if You can't use the other read-procedures. adr is
  122. the address to put the data to, and  len  determines  how  many  bytes  the
  123. procedure  should read. The result is the number bytes really readed. If no
  124. error occurs, the result should be equal len. If You  for  example  try  to
  125. read  over  the end of the file, the result will be less than len and f.res
  126. is equal endOfFile.
  127.  
  128.  
  129. The procedures to write data to a file:
  130.  
  131. PROCEDURE Write(VAR f: File; block: ARRAY OF BYTE): BOOLEAN;
  132.  
  133. Writes  LEN(block)  Bytes  to  the  file.  block  is  compatible  with  all
  134. datatypes.
  135.  
  136. PROCEDURE WriteChar(VAR f: File; ch: BYTE): BOOLEAN;
  137.  
  138. Writes  a  single character to the file. Instead of WriteChar() You can use
  139. Write(), but TurboFiles.WriteChar() is much faster.
  140.  
  141. PROCEDURE WriteString(VAR f: File; str: ARRAY OF CHAR): BOOLEAN;
  142.  
  143. Writes the string str to the file using  WriteChar().  The  string  is  not
  144. terminated  with  a  linefeed.  If  You will write the next string to a new
  145. line, You must use WriteChar(f,ASCII.lf) OR WriteLn(f).
  146.  
  147. PROCEDURE WriteBytes(VAR f: File; adr: Exec.ADDRESS; len: LONGINT): BOOLEAN;
  148.  
  149. This is again a low-level-procedure. Use it only if You can't use the other
  150. write-procedures. adr is the memory location from which WriteBytes()  takes
  151. the data, and len determines how many Bytes will be written to the file.
  152.  
  153. Now the procedures GetPos(), SetPos() and Size():
  154.  
  155. PROCEDURE GetPos(VAR f: File): LONGINT;
  156.  
  157. GetPos()  gives  You  the  current  position in the file, measured from the
  158. beginning of the file. If there was an error  in  a  former  operation  and
  159. f.res#done, then this procedure will return -1.
  160.  
  161. PROCEDURE SetPos(VAR f: File; offset: LONGINT; mode: LONGINT): BOOLEAN;
  162.  
  163. With  this  procedure  You  can  jump  to  any position in the file. offset
  164. determines the new position. If mode=beginning, then offset is the distance
  165. from the beginning of the file. If mode=end, offset is  the  distance  from
  166. the  end  of  the  file.  If  mode=current,  then we will move offset Bytes
  167. forward (if offset>0) or backward (if offset<0). If You try to  move  to  a
  168. position out of the file, then f.res will get the value seekError.
  169.  
  170. PROCEDURE Size(VAR f: File): LONGINT;
  171.  
  172. Size() gives You the current size of the file in Bytes. If f.res#done, this
  173. procedure will return -1.
  174.  
  175. PROCEDURE Search(VAR f: File; str: ARRAY OF BYTE; len: INTEGER): LONGINT;
  176.  
  177. This  procedure  searches  for  the  string  str,  starting  at the current
  178. position. Only the first len Bytes of str are significant. If str is found,
  179. then Search() set the position in the file to  this  location  and  returns
  180. this position. If the search fails, -1 is returned and f.res # done.
  181.  
  182. PROCEDURE Close(VAR f: File): BOLEAN;
  183.  
  184. Closes an open file. You should use Close() to close an  open  file  if  You
  185. don't  want  to  work  with  it  any more. When a program terminates without
  186. closing all open Files, then this module closes all Dos-Files, but it  saves
  187. NOT  the  content of the buffer! If the file is allready closed ( because an
  188. Open() was not succesfull, or because of an former  call  of  Close(),  this
  189. Procedure  will do nothing and only return FALSE. Although  if f.res has the
  190. value notOpen, then this Procedure returns without doing anything.
  191. For the programer means this: If a file-variable is initialized by a  call
  192. of  Open(),  You  can call Close() at any time without worrying about if the
  193. file is open or not. There is one problem left. If Your  program  terminates
  194. before  You call Open(), and there is a CLOSE-statment in Your program which
  195. calls  Close(),  it  can  hapen  that  Close()  works  on  an  uninitialized
  196. file-variable.  To  avoid this, it is a save way to set f.res to notOpen at
  197. the begin of Your program.
  198.  
  199. To use the following procedures, the file MUST be close!
  200.  
  201. PROCEDURE DeleteFile(name: ARRAY OF CHAR): BOOLEAN;
  202.  
  203. Deletes a file. The same as Dos.Delete().
  204.  
  205. PROCEDURE Exists(name: ARRAY OF CHAR; VAR size: LONGINT): BOOLEAN;
  206.  
  207. Exists()  checks  if  or  if  not  a  file or directory exists. If a file or
  208. directory called name exists, TRUE is  returned.  IF  it  is  a  file,  size
  209. contains  the  size of this file in bytes. If it is a directory, size is set
  210. to -1.
  211.  
  212. PROCEDURE Code(fileName, codeWord: ARRAY OF CHAR; decode: BOOLEAN):BOOLEAN;
  213.  
  214. With  this procedure You can code and decode any file. codeWord is a string
  215. which can contain any character  except  0X.  If  decode  is  true,  Code()
  216. decodes the file. The coded file has the same size and name as the original
  217. file.
  218.  
  219. HINT:  If  any procedure fails, it will set f.res to a value different from
  220. done. From this time on all following fileoperations are ignored.  Normally
  221. You  should close the file in this case, but if the error is for example of
  222. the type endOfFile, You can set f.res to done and go on working  with  this
  223. file.
  224.  
  225. I tested this module on an A1000 with KS and WB 1.3, but is should work
  226. on other Amiga's too!
  227.  
  228. Stefan Salewski,    09-Jun-1991
  229.  
  230.  
  231.